xfi:relationship.type*=xfi:concept-relationships( $source as xs:QName, $linkrole as xs:string?, $arcrole as xs:string, $axis as xs:string, $generations as xs:nonNegativeInteger?, $linkname as xs:QName?, $arcname as xs:QName?)

Last updated on 18-06-2013 at 14:00:00Z.

Returns a sequence containing the set of effective relationships with the specified relationship to the source concept.

Documentation

An example of the use of this function to implement calculation linkbase validation with weighted values summation is provided in the test case 61100 ConceptRelationsFilter Processing.xml v21. The files of this test case are attached in this directory as an illustration of the concept-relationships use. The schema file is nav-rel-test1.xsd, the calc linkbase file is nav-rel-test1-detached-calculation.xml, the formula assertion file is calc-lb-exact-sum-weighted-children-formula.xml, and an instance file is calc-lb-exact-sum-weighted-children-instance-ok.xml. Comments in the formula assertion file, calc-lb-exact-sum-weighted-children-formula.xml, describe its operation. The generalVariable, $linkRole, binds one-by-one to each link role that has summation-item arcs. The factVariable, $parent, to every fact in instance. (An alternative approach in calc-lb-exact-sum-weighted-children-formula2.xml binds $parent only to concepts in $linkRole that are from-concepts on effective relationships). The factVariable, $family, binds to the sequence of aspect-related facts (ignoring concept aspect). The generalVariable, $rels, binds to the sequence of effective relationship arcs of children of $parent. The factVariable, $weightedChildValues, binds to the sequence of child values multiplied by the weight on the arc from $parent.

OIM Status

Supported

Parameters

Name	Type	Details
source	xs:QName	The QName of the source concept from which to begin navigation. The special QName xfi:root is recognized when it is desired to retrieve relations to descendants from the 'root' level (who have no parents).
linkrole	xs:string?	The linkrole value that specifies the network of effective relationships on the specified axis from the member used as the origin. If omitted ("()" or "''") then the default link role is used.
arcrole	xs:string	The arcrole value that specifies the network of effective relationships.
axis	xs:string	The axis value MUST be one of: descendant child ancestor parent sibling sibling-or-descendant If the axis value is 'descendant' then the relationships returned include those to concepts that are descendants of the source concept QName, in the linkrole network of arcrole effective relationships. ('child' is the same as descendant and generations = 1.) For the special source QName, xfi:root, descendants are those from the topmost level (where the source concepts have no parents). If the axis value is 'ancestor' then the relationships returned include those from concepts that are ancestors of the source concept QName, in the linkrole network of arcrole effective relationships. (For parent, use ancestor and generations = 1.) Ancestors of a root concept is an empty result sequence, so a way to test that a concept is a root node is to test for an empty result set of parent relationships. If the axis value is 'sibling' then the relationships returned include those concepts that are siblings of the parents as the source, in the linkrole network of arcrole effective relationships. (A concept with multiple parent relationships has, as siblings, those concepts with the same parent relationships.) If the source concept is at root level (having no parent relationships), then its sibling concepts are other root concepts, but as these other root concepts have no parent relationships, there are no sibling relationships to any root concept, and an empty sequence is always produced for sibling relationships of a root concept. If the axis value is 'sibling-or-descendant' then the result set includes siblings, per above, plus descendant relationships. The generations count is the number of descendant generations, and generations=0 means all descendants.
generations	xs:nonNegativeInteger?	This parameter is optional. The generations value specifies a limit of number of generations (for descendant or ancestor), or zero (if unlimited generations navigation is desired. Generations=1 and descendant axis means obtain only children, generations=2 obtains children and grandchildren, and generations=0 means all descendants. Generations must be omitted or 1 for a parent, child, or sibling axis. Generations may be omitted for ancestor or descendant axes, in which case 0 (all ancestors or descendants) is assumed. In any case if a descendant or ancestor concept repeats in the path from the source, it is not navigated further for unlimited generations navigation (generations=0), but it is navigated further for limited generations navigation. Thus it is not wise to put a high integer on generations count if directed cycles may exist. A demonstration of this issue is in function test cases v-09 and V-09a. In V-09 navigation starts at A1, for descendants (not self) for unlimited generations. In this case A1 is not included first in the output (because of missing '-or-self') but A1 is a descendant of A13 (A1->A13->A1) so the A1 occurence under A13 is included in the output, but no further navigation from the repeat (directed cycle) beneath A1 is navigated. In V-09c 7 generations are requested, to show that the directed cycle is followed for 7 generations.
linkname	xs:QName?	This parameter is optional. If absent the arcrole and linkrole uniquely determine a base set, such as when only standard link elements are used with standard arc elements and arc roles, or generic arcs have only one possible link element that may contain them. If provided then generations must also be provided. If provided then this parameter specifies the link element to be included in the result set. If omitted, or "()", then the link element QName is not used to determine an applicable base set network.
arcname	xs:QName?	This parameter is optional. If absent the arcrole and linkrole uniquely determine a base set, such as when only standard arc elements are used with standard link elements and arc roles, or generic arcs have only one possible arc element. If provided then link name and generations must also be provided. If provided then this parameter specifies the arc element to be included in the result set. If omitted, or "()", then the arc element QName is not used to determine an applicable base set network.

Output

Type: xfi:relationship.type*

Returns a sequence of effective relationships that are implementation-defined objects or relationship surrogates. These objects are opaque as they may be used only as function arguments, but not for direct XPath navigation or value access. The implementation-defined objects or relationship surrogates are intended to be only used as parameters to other functions such as xfi:relationship-from-concept, xfi:relationship-to-concept, xfi:relationship-attribute, xfi:relationship-element, xfi:link-attribute, and xfi:link-element.

The implementation-defined objects may be nodes or may be atomic elements, the consuming application should allow both kinds of implementation strategies, but not access the content of such nodes or value of such elements. xfi:relationship.type would be defined as xs:anyType.

The order is the effective relationships order after consideration of arc order value, prohibition, and override.

The tree-walk of multiple generations is in depth-first order (or the inverse for ancestors), a node's descendants are recursively inserted in the result subsequences prior to continuing with siblings.

Errors

Code	Details
xfie:InvalidConceptRelationParameters	This error MUST be thrown if an axis other than descendant, child, ancestor, parent, sibling or sibling-or-descendant is specified or if a generations value of other than 1 is specified for a sibling, child, or parent axis.

Conformance suite

90507 xfi.concept-relationships testcase.xml [ download ]

Owners

Name	Affiliation	Email	Start	End
Herm Fischer	UBMatrix / Mark V Systems	fischer@markv.com	01-09-2008 at 00:00:00
Richard Ashby	CoreFiling	rna@corefiling.com	18-06-2013 at 14:00:00Z
Stuart Barker	CoreFiling	dsb@corefiling.com	31-08-2016 at 23:00:00Z

Revisions

Name	On	Details
Herm Fischer	12-12-2008 at 00:00:00	Created the predecessor xfi.navigate-relationships function definition.
Herm Fischer	28-10-2009 at 20:00:00	Evolved this function definition from xfi.navigate-relationships.
Herm Fischer	01-11-2009 at 15:00:00	Changed siblings with descendants axis to sibling-or-descendant. Updated generations to be optional, with defaults as noted, per suggestion by Victor Morilla.
Herm Fischer	12-12-2009 at 00:00:00	Removed reference to dynamically loaded instances from the xbrlinstance input.
Herm Fischer	08-03-2010 at 00:00:00	Added optional linkname and arcname parameters due to base spec agreement that these element names are required to determine base set when multiple link or arc elements may be used with the same arc and link roles. Changed the returned objects to be implementation defined, opaque, and not specified to return xl:arc elements.
Herm Fischer	07-09-2010 at 00:00:00	Incorporated feedback from Hitoshi Okumura. Changed output type from xfi:relationship.type to xfi:relationship.type* to allow sequence results as described. Changed input types to "?" for optional parameters linkrole, generations, linkname, arcname.
Herm Fischer	09-09-2010 at 00:00:00	Changed role URIs to strings for cast-less coding and to be similar to fn:QName's $paramURI, an xs:string.
Herm Fischer	16-10-2010 at 00:00:00	Incorporated feedback from Hitoshi Okumura, fixing typo, reference to "V-09A" changed to "V-09c" for 7-generations test.
Herm Fischer	24-03-2011 at 08:00:00	Incorporated feedback from Hitoshi Okumura. Changed generations parameter from xs:integer to xs:nonNegativeInteger to be same as conceptRelation filter.
Richard Ashby	18-06-2013 at 14:00:00Z	As per agreement on FWG call 2013/06/13, removed optional instance parameter and created separate CR function that uses it.
Stuart Barker	31-08-2016 at 23:00:00Z	Added error code InvalidConceptRelationParameters.